---
title: Mutations in Apollo Kotlin
---

**Mutations** are GraphQL operations that _modify_ back-end data. As a convention in GraphQL, [queries](./queries/) are read operations and mutations are write operations.

## Defining a mutation

You define a mutation in your app just like you define a query, except you use the `mutation` keyword. Here's an example mutation for upvoting a post:

```graphql title="UpvotePost.graphql"
mutation UpvotePost($postId: Int!) {
  upvotePost(postId: $postId) {
    id
    votes
  }
}
```

And here's an example schema snippet that supports this mutation:

```graphql title="schema.graphqls"
type Mutation {
  upvotePost(postId: Int!): Post
}

type Post {
  id: Int!
  votes: Int!
  content: String!
}
```

The fields of the `Mutation` type (such as `upvotePost` above) usually describe the actions that mutations can perform. These fields usually take one or more arguments, which specify the data to create or modify.

### Mutation return types

The return type of a `Mutation` field usually includes the backend data that's been modified. This provides the requesting client with immediate information about the result of the mutation.

In the example above, `upvotePost` returns the `Post` object that's just been upvoted. Here's an example response:

```json
{
  "data": {
    "upvotePost": {
      "id": "123",
      "votes": 5
    }
  }
}
```

For more information on mutation return types, see [Designing mutations](https://www.apollographql.com/docs/apollo-server/schema/schema/#designing-mutations).


## Generating mutation classes

Similar to queries, mutations are represented by instances of generated classes, conforming to the `Mutation` interface.
Constructor arguments are used to define mutation variables. You pass a mutation object
to `ApolloClient.mutation(mutation)` to send the mutation to the server, execute it, and receive typed results:


```kotlin
val upvotePostMutation = UpvotePostMutation(postId = 3)

val response = apolloClient.mutation(upvotePostMutation).execute()
```

## Using fragments in mutation results

In many cases, you'll want to use mutation results to update your UI. [Fragments](./fragments/#named-fragments) are a great way to share result handling between queries and mutations:

```graphql
mutation UpvotePost($postId: Int!) {
  upvotePost(postId: $postId) {
    ...PostDetails
  }
}
```

## Passing input objects

The GraphQL type system includes [input objects](http://graphql.org/learn/schema/#input-types) as a way to pass complex values to fields. Input objects are often used for mutation variables, because they provide a compact way to pass in objects to be created:

```graphql
mutation CreateReviewForEpisode($episode: Episode!, $review: ReviewInput!) {
  createReview(episode: $episode, review: $review) {
    stars
    commentary
  }
}
```

```kotlin
val reviewInput = ReviewInput(stars = 5, commentary = "This is a great movie!")

val response = apolloClient.mutation(CreateReviewForEpisodeMutation(episode = Episode.NEWHOPE, review = reviewInput)).execute()
```
